Specifying the Data Source16

Graphics importer components use QuickTime data handler components to obtain their data. Applications, however, will use the graphics importer component functions described in this section, rather than directly calling a data handler. These functions allow the data source to be a file, a handle, or a QuickTime data reference.

You do not need to call the functions in this section if you use one of the GetGraphicsImporter functions. The GetGraphicsImporter functions automatically set the graphics importer component's data source. You only need to use these functions if you open the graphics importer component directly.

GraphicsImportSetDataFile

Specifies the file that the graphics data resides in.



 
 pascal ComponentResult GraphicsImportSetDataFile (

                     GraphicsImportComponent ci,

                     const FSSpec *theFile);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
theFile: A pointer to the file specification of the file containing the graphics data.

DISCUSSION

The file will be opened for read access.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportGetDataFile

Returns the file that the graphics data resides in.



 
 pascal ComponentResult GraphicsImportGetDataFile (

                     GraphicsImportComponent ci,

                     FSSpec *theFile);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
theFile: A pointer in which to return the file specification of the file containing the graphics data.

DISCUSSION

You use this function to get the file system specification record for the file that the graphics data resides in. If the data source is not a file, the function returns paramErr .

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportSetDataHandle

Specifies the handle that the graphics data resides in.



 
 pascal ComponentResult GraphicsImportSetDataHandle (

                     GraphicsImportComponent ci,

                     Handle h);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
h: Specifies a handle containing graphics data. The format of the data in the handle is the same as that found in a file.

DISCUSSION

The graphics importer component doesn't make a copy of this data. Therefore, you must not dispose this handle until the graphics importer has been closed.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available.

GraphicsImportGetDataHandle

Returns the handle that the graphics data resides in.



 
 pascal ComponentResult GraphicsImportGetDataHandle (

                     GraphicsImportComponent ci,

                     Handle *h);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
h: A pointer in which to return a handle containing the graphics data.

DISCUSSION

You use this function to get the handle that the graphics data resides in. If the data source is not a handle, the function returns paramErr . The handle belongs to the component instance. You shouldn't dispose of it.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportSetDataReference

Specifies the data reference that the graphics data resides in.



 
 pascal ComponentResult GraphicsImportSetDataReference (

                     GraphicsImportComponent ci,

                     Handle dataRef,

                     OSType dataRefType);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
dataRef: A QuickTime data reference.
dataRefType: The data reference type.

DISCUSSION

Applications typically do not use this function. The GraphicsImportSetDataFile and GraphicsImportSetDataHandle functions both call this function, with the appropriate data reference and data reference type. This function makes a copy of the passed data reference, so it is safe to dispose of the handle immediately after the call.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportGetDataReference

Returns the data reference that the graphics data resides in.



 
 pascal ComponentResult GraphicsImportGetDataReference (

                     GraphicsImportComponent ci,

                     Handle *dataRef,

                     OSType *dataRefType);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
dataRef: A pointer in which to return a QuickTime data reference.
dataRefType: A pointer to receive the data reference type.

DISCUSSION

You use this function to get the data reference that the graphics data resides in. Both the dataRef and dataRefType parameters may be set to nil if the corresponding information is not desired. The GraphicsImportGetDataHandle and GraphicsImportGetDataFile functions call GraphicsImportGetDataReference and then manipulate the result accordingly. The caller should dispose of the returned dataRef .

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportSetDataReferenceOffsetAndLimit

Specifies the data reference starting offset and data size limit.



 
 pascal ComponentResult GraphicsImportSetDataReferenceOffsetAndLimit (

                     GraphicsImportComponent ci,

                     unsigned long offset,

                     unsigned long limit);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
offset: The byte offset of the image data from the beginning of the data reference.
limit: A pointer to a value specifying the offset of the byte following the last byte of the image data.

DISCUSSION

A data reference typically refers to an entire file. However, there are times when the data being referenced is embedded in a larger file. In these cases, it is necessary to indicate where the data begins in the data reference and where it ends. This function lets you specify the starting offset and ending offset. All requests to read data are then relative to the specified offset, and are pinned to the data size, so the graphics import component cannot accidentally read off the end (or beginning) of the segment.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportGetDataReferenceOffsetAndLimit

Returns the data reference starting offset and data size limit.



 
 pascal ComponentResult GraphicsImportGetDataReferenceOffsetAndLimit (

                     GraphicsImportComponent ci,

                     unsigned long *offset,

                     unsigned long *limit);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
offset: A pointer to a value specifying the byte offset of the image data from the beginning of the data reference.
limit: The offset of the byte following the last byte of the image data.

DISCUSSION

This function returns the values set by the GraphicsImportSetDataReferenceOffsetAndLimit function. By default, offset is 0 and limit is MaxInt (2^32 - 1).

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available